NAZWA¶

ncurses - pakiet obsługi CRT i jego optymalizacji

STRESZCZENIE¶

#include <curses.h>

OPIS¶

Uwaga! To tłumaczenie może być nieaktualne!

Funkcje biblioteki curses dają użytkownikowi niezależne od terminala metody obsługiwania ekranów znakowych z sensowną optymalizacją. Ta implementacja to ,,nowe curses'' (ncurses). Jest ona zatwierdzonym zamiennikiem dla klasycznych curses z 4.4BSD, których rozwoju zaprzestano.

Funkcje ncurses emulują bibliotekę curses(3X) Systemu Vr4, a także standard XPG4 (XSI curses), lecz biblioteka ncurses jest wolnodostępna w postaci źródłowej. Różnice między curses z SVr4 podsumowano w sekcjach ROZSZERZENIA i BŁĘDY, występujących poniżej, a opisano szczegółowo w takich samych sekcjach stron podręcznika systemowego poświęconych poszczególnym funkcjom.

Program, który korzysta z tych funkcji, musi być skonsolidowany z opcją -lncurses (lub jeśli został wygenerowany) z biblioteką debuggową -lncurses_g. Biblioteka ncurses_g generuje logi śledzenia (plik o nazwie 'trace', w bieżącym katalogu), które opisują akcje curses.

Pakiet ncurses obsługuje: działanie na ekranie, oknach i padach; wyjście do okien i padów; odczytywanie wejścia z terminala; sterowanie terminalem oraz opcje wejścia/wyjścia curses; funkcje zapytań środowiskowych; działanie na kolorach; używanie klawiszy o miękkich etykietach; właściwości terminfo; i dostęp do niskopoziomowych funkcji obsługi terminala.

Aby zainicjalizować pakiet, należy na samym początku wywołać funkcję initscr, lub newterm. Przed wyjściem należy wywołać funkcję endwin. Aby uzyskać wejście znakowe znak-po-znaku bez echa (większość interaktywnie zorientowanych programów tego chce), powinno się użyć następującej sekwencji:

initscr(); cbreak(); noecho();

Większość programów chętnie wykorzystuje też sekwencje:

nonl();
intrflush(stdscr, FALSE);
keypad(stdscr, TRUE);

Przed uruchomieniem programu curses, należy ustawić <tab stops> (pozycje tabulacji) terminala, oraz wysłać doń łańcuchy inicjujące. Można tego dokonać, wywołując polecenie tput init po uprzednim wyeksportowaniu zmiennej środowiskowej TERM. Odpowiedzialny za to jest tset(1). [Szczegóły - zobacz terminfo(5).]

Biblioteka curses zezwala na działanie na strukturach danych, nazywanych oknami, o których można myśleć jak o dwuwymiarowych tablicach znaków, reprezentujących część lub całość ekranu CRT. Dostarczane jest domyślne okno, o nazwie stdscr, którego wymiary odpowiadają ekranowi terminala. Inne okna można utworzyć przy użyciu funkcji newwin.

Zauważ, że curses nie obsługuje zachodzących okien - jest to robione przez bibliotekę panels(3x). Znaczy to, że możesz albo używać stdscr, albo podzielić ekran na okna i nie używać stdscr w ogóle. Łączenie tych dwóch spowoduje niepraktyczne i niepożądane efekty.

Do okien można odnosić się poprzez zmienne zadeklarowane jako WINDOW *. Działań na tych strukturach dokonuje się funkcjami opisanymi na tej stronie oraz w innych miejscach stron podręcznika ncurses. Najbardziej podstawowymi funkcjami są move i addch. Ogólniejsze wersje tych funkcji figurują pod nazwami zaczynającymi się od w i umożliwiają podanie okna. Funkcje nie zaczynające się od w działają na stdscr.

Po użyciu funkcji działania na oknie, wywoływany jest refresh, nakazujący curses, by ekran CRT zaczął wyglądać tak jak stdscr. Znaki okna są właściwie typu chtype (znak i dane atrybutu), więc dane o znaku można przechowywać w nim samym.

Można też operować szczególnymi oknami, padami. Okna te nie są ograniczone rozmiarami ekranu, a ich zawartość nie musi być w całości wyświetlana. Więcej szczegółów znajdziesz w curs_pad(3X).

Oprócz rysowania na ekranie znaków, mogą być obsługiwane atrybuty i kolory, a więc znaki mogą pokazywać się w trybach takich jak podkreślenie, inwersja, lub w kolorze, o ile terminal na to pozwala. Można wyświetlać znaki składające się na linie. Na wejściu, ncurses potrafi tłumaczyć klawisze strzałek i funkcyjne, które przekazują sekwencje eskejpowe, na zwykłe wartości. Atrybuty wideo, znaki rysowania linii i nazwy wartości wejściowych są zdefiniowane w <curses.h> i mają nazwy typu A_REVERSE, ACS_HLINE, czy KEY_LEFT.

Jeśli ustawiono zmienne środowiskowe LINES i COLUMNS, lub jeśli program jest uruchomiony w środowisku okienkowym, to informacje o rozmiarze ekranu przesłonią dane odczytywane z terminfo.

Jeśli zdefiniowana jest zmienna środowiskowa TERMINFO, to każdy program używający curses będzie szukał najpierw lokalnej definicji terminala, a dopiero potem zajrzy do standardowego miejsca. Np. Jeśli TERM jest ustawione na att4424, to wkompilowana definicja terminala jest znajdywana w

/usr/lib/terminfo/a/att4424.

(a jest kopiowane z pierwszej litery att4424, aby zapobiec tworzeniu wielkich katalogów.) Jednak jeśli ustawiono TERMINFO, np. na wartość $HOME/myterms, to curses zajrzy wpierw do

$HOME/myterms/a/att4424,

a jeśli to zawiedzie, do

/usr/lib/terminfo/a/att4424.

Jest to przydatne dla rozwijania eksperymentalnych definicji, lub gdy nie ma praw zapisu do /usr/lib/terminfo.

Zmienne całkowite LINES i COLS są zdefiniowane w <curses.h> i są wypełniane przez initscr wartościami, odpowiadającymi rozmiarowi ekranu. Stałe TRUE i FALSE mają odpowiednio wartości 1 i 0.

Zmienne curses definiują również zmienną WINDOW *curscr, która jest używana do pewnych niskopoziomowych operacji, jak np. oczyszczanie i odświeżanie ekranu, zawierającego śmieci. curscr może być użyte tylko w niektórych funkcjach.

Nazwa funkcji    Nazwa strony podręcznika
___________________________________________
addch                  curs_addch(3X)
addchnstr              curs_addchstr(3X)
addchstr               curs_addchstr(3X)
addnstr                curs_addstr(3X)
addstr                 curs_addstr(3X)
attroff                curs_attr(3X)
attron                 curs_attr(3X)
attrset                curs_attr(3X)
baudrate               curs_termattrs(3X)
beep                   curs_beep(3X)
bkgd                   curs_bkgd(3X)
bkgdset                curs_bkgd(3X)
border                 curs_border(3X)
box                    curs_border(3X)
can_change_color       curs_color(3X)
cbreak                 curs_inopts(3X)
clear                  curs_clear(3X)
clearok                curs_outopts(3X)
clrtobot               curs_clear(3X)
clrtoeol               curs_clear(3X)
color_content          curs_color(3X)
copywin                curs_overlay(3X)
curs_set               curs_kernel(3X)
def_prog_mode          curs_kernel(3X)
def_shell_mode         curs_kernel(3X)
del_curterm            curs_terminfo(3X)
delay_output           curs_util(3X)
delch                  curs_delch(3X)
deleteln               curs_deleteln(3X)
delscreen              curs_initscr(3X)
delwin                 curs_window(3X)
derwin                 curs_window(3X)
doupdate               curs_refresh(3X)
dupwin                 curs_window(3X)
echo                   curs_inopts(3X)
echochar               curs_addch(3X)
endwin                 curs_initscr(3X)
erase                  curs_clear(3X)
erasechar              curs_termattrs(3X)
filter                 curs_util(3X)
flash                  curs_beep(3X)
flushinp               curs_util(3X)
getbegyx               curs_getyx(3X)
getch                  curs_getch(3X)
getmaxyx               curs_getyx(3X)
getmouse               curs_mouse(3X)*
getparyx               curs_getyx(3X)
getstr                 curs_getstr(3X)
getsyx                 curs_kernel(3X)
getwin                 curs_util(3X)
getyx                  curs_getyx(3X)
halfdelay              curs_inopts(3X)
has_colors             curs_color(3X)
has_ic                 curs_termattrs(3X)
has_il                 curs_termattrs(3X)
hline                  curs_border(3X)
idcok                  curs_outopts(3X)
idlok                  curs_outopts(3X)
immedok                curs_outopts(3X)
inch                   curs_inch(3X)
inchnstr               curs_inchstr(3X)
inchstr                curs_inchstr(3X)
init_color             curs_color(3X)
init_pair              curs_color(3X)
initscr                curs_initscr(3X)
innstr                 curs_instr(3X)
insch                  curs_insch(3X)
insdelln               curs_deleteln(3X)
insertln               curs_deleteln(3X)
insnstr                curs_insstr(3X)
insstr                 curs_insstr(3X)
instr                  curs_instr(3X)
intrflush              curs_inopts(3X)
is_linetouched         curs_touch(3X)
is_wintouched          curs_touch(3X)
isendwin               curs_initscr(3X)
keyname                curs_util(3X)
keypad                 curs_inopts(3X)
killchar               curs_termattrs(3X)
leaveok                curs_outopts(3X)
longname               curs_termattrs(3X)
meta                   curs_inopts(3X)
mouseinterval          curs_mouse(3X)*
mousemask              curs_mouse(3X)*
move                   curs_move(3X)
mvaddch                curs_addch(3X)
mvaddchnstr            curs_addchstr(3X)
mvaddchstr             curs_addchstr(3X)
mvaddnstr              curs_addstr(3X)
mvaddstr               curs_addstr(3X)
mvcur                  curs_terminfo(3X)
mvdelch                curs_delch(3X)
mvderwin               curs_window(3X)
mvgetch                curs_getch(3X)
mvgetstr               curs_getstr(3X)
mvinch                 curs_inch(3X)
mvinchnstr             curs_inchstr(3X)
mvinchstr              curs_inchstr(3X)
mvinnstr               curs_instr(3X)
mvinsch                curs_insch(3X)
mvinsnstr              curs_insstr(3X)
mvinsstr               curs_insstr(3X)
mvinstr                curs_instr(3X)
mvprintw               curs_printw(3X)
mvscanw                curs_scanw(3X)
mvwaddch               curs_addch(3X)
mvwaddchnstr           curs_addchstr(3X)
mvwaddchstr            curs_addchstr(3X)
mvwaddnstr             curs_addstr(3X)
mvwaddstr              curs_addstr(3X)
mvwdelch               curs_delch(3X)
mvwgetch               curs_getch(3X)
mvwgetstr              curs_getstr(3X)
mvwin                  curs_window(3X)
mvwinch                curs_inch(3X)
mvwinchnstr            curs_inchstr(3X)
mvwinchstr             curs_inchstr(3X)
mvwinnstr              curs_instr(3X)
mvwinsch               curs_insch(3X)
mvwinsnstr             curs_insstr(3X)
mvwinsstr              curs_insstr(3X)
mvwinstr               curs_instr(3X)
mvwprintw              curs_printw(3X)
mvwscanw               curs_scanw(3X)
napms                  curs_kernel(3X)
newpad                 curs_pad(3X)
newterm                curs_initscr(3X)
newwin                 curs_window(3X)
nl                     curs_outopts(3X)
nocbreak               curs_inopts(3X)
nodelay                curs_inopts(3X)
noecho                 curs_inopts(3X)
nonl                   curs_outopts(3X)
noqiflush              curs_inopts(3X)
noraw                  curs_inopts(3X)
notimeout              curs_inopts(3X)
overlay                curs_overlay(3X)
overwrite              curs_overlay(3X)
pair_content           curs_color(3X)
pechochar              curs_pad(3X)
pnoutrefresh           curs_pad(3X)
prefresh               curs_pad(3X)
printw                 curs_printw(3X)
putp                   curs_terminfo(3X)
putwin                 curs_util(3X)
qiflush                curs_inopts(3X)
raw                    curs_inopts(3X)
redrawwin              curs_refresh(3X)
refresh                curs_refresh(3X)
reset_prog_mode        curs_kernel(3X)
reset_shell_mode       curs_kernel(3X)
resetty                curs_kernel(3X)
restartterm            curs_terminfo(3X)
ripoffline             curs_kernel(3X)
savetty                curs_kernel(3X)
scanw                  curs_scanw(3X)
scr_dump               curs_scr_dump(3X)
scr_init               curs_scr_dump(3X)
scr_restore            curs_scr_dump(3X)
scr_set                curs_scr_dump(3X)
scrl                   curs_scroll(3X)
scroll                 curs_scroll(3X)
scrollok               curs_outopts(3X)
set_curterm            curs_terminfo(3X)
set_term               curs_initscr(3X)
setscrreg              curs_outopts(3X)
setsyx                 curs_kernel(3X)
setterm                curs_terminfo(3X)
setupterm              curs_terminfo(3X)
slk_attroff            curs_slk(3X)
slk_attron             curs_slk(3X)
slk_attrset            curs_slk(3X)
slk_clear              curs_slk(3X)
slk_init               curs_slk(3X)
slk_label              curs_slk(3X)
slk_noutrefresh        curs_slk(3X)
slk_refresh            curs_slk(3X)
slk_restore            curs_slk(3X)
slk_set                curs_slk(3X)
slk_touch              curs_slk(3X)
standend               curs_attr(3X)
standout               curs_attr(3X)
start_color            curs_color(3X)
subpad                 curs_pad(3X)
subwin                 curs_window(3X)
syncok                 curs_window(3X)
termattrs              curs_termattrs(3X)
termname               curs_termattrs(3X)
tgetent                curs_termcap(3X)
tgetflag               curs_termcap(3X)
tgetnum                curs_termcap(3X)
tgetstr                curs_termcap(3X)
tgoto                  curs_termcap(3X)
tigetflag              curs_terminfo(3X)
tigetnum               curs_terminfo(3X)
tigetstr               curs_terminfo(3X)
timeout                curs_inopts(3X)
touchline              curs_touch(3X)
touchwin               curs_touch(3X)
tparm                  curs_terminfo(3X)
tputs                  curs_termcap(3X)
tputs                  curs_terminfo(3X)
typeahead              curs_inopts(3X)
unctrl                 curs_util(3X)
ungetch                curs_getch(3X)
ungetmouse             curs_mouse(3X)*
untouchwin             curs_touch(3X)
use_env                curs_util(3X)
vidattr                curs_terminfo(3X)
vidputs                curs_terminfo(3X)
vline                  curs_border(3X)
vwprintw               curs_printw(3X)
vwscanw                curs_scanw(3X)
waddch                 curs_addch(3X)
waddchnstr             curs_addchstr(3X)
waddchstr              curs_addchstr(3X)
waddnstr               curs_addstr(3X)
waddstr                curs_addstr(3X)
wattroff               curs_attr(3X)
wattron                curs_attr(3X)
wattrset               curs_attr(3X)
wbkgd                  curs_bkgd(3X)
wbkgdset               curs_bkgd(3X)
wborder                curs_border(3X)
wclear                 curs_clear(3X)
wclrtobot              curs_clear(3X)
wclrtoeol              curs_clear(3X)
wcursyncup             curs_window(3X)
wdelch                 curs_delch(3X)
wdeleteln              curs_deleteln(3X)
wechochar              curs_addch(3X)
wenclose               curs_mouse(3X)*
werase                 curs_clear(3X)
wgetch                 curs_getch(3X)
wgetnstr               curs_getstr(3X)
wgetstr                curs_getstr(3X)
whline                 curs_border(3X)
winch                  curs_inch(3X)
winchnstr              curs_inchstr(3X)
winchstr               curs_inchstr(3X)
winnstr                curs_instr(3X)
winsch                 curs_insch(3X)
winsdelln              curs_deleteln(3X)
winsertln              curs_deleteln(3X)
winsnstr               curs_insstr(3X)
winsstr                curs_insstr(3X)
winstr                 curs_instr(3X)
wmove                  curs_move(3X)
wnoutrefresh           curs_refresh(3X)
wprintw                curs_printw(3X)
wredrawln              curs_refresh(3X)
wrefresh               curs_refresh(3X)
wresize                curs_resize(3x)*
wscanw                 curs_scanw(3X)
wscrl                  curs_scroll(3X)
wsetscrreg             curs_outopts(3X)
wstandend              curs_attr(3X)
wstandout              curs_attr(3X)
wsyncdown              curs_window(3X)
wsyncup                curs_window(3X)
wtimeout               curs_inopts(3X)
wtouchln               curs_touch(3X)
wvline                 curs_border(3X)

WARTOŚĆ ZWRACANA¶

Funkcje, które zwracają integer, zwracają ERR w wypadku błędu, a po sukcesie dowolny inny integer. (chyba że zaznaczono inaczej w opisie funkcji).

Wszystkie makra zwracają wartość wersji w, poza setscrreg, wsetscrreg, getyx, getbegyx, getmaxyx. Wartości zwracane setscrreg, wsetscrreg, getyx, getbegyx, i getmaxyx są niezdefiniowane (np. nie powinny być używane jako instrukcje prawej strony przypisań).

Funkcje, które zwracają wskaźniki, po błędzie zwracają NULL.

ZOBACZ TAKŻE¶

terminfo(5) oraz strony 3X , których nazwa zaczyna się od "curs_".

ROZSZERZENIA¶

Biblioteka curses może być skompilowana z opcją (-DTERMCAP_FILE), która powoduje skok wstecz, do starodawnego pliku /etc/termcap, jeśli nie ma odpowiedniego wpisu w terminfo. Użycie tej właściwości nie jest zalecane, gdyż w zasadzie włącza ona do kodu startowego curses cały kompilator termcapa.

Kompilowanie z -DTERMCAP_FILE zmienia sekwencję inicjalizacji biblioteki, na sposób podobny do 4.4BSD curses. Jeśli nie ma żadnego terminfo, opowiadającego TERM, to biblioteka zaczyna szukać wpisów termcap. Robi to w następujących miejscach: (1) jeśli TERMINFO nie jest zdefiniowane, w pliku o nazwie TERMCAP_FILE; (2) jeśli zdefiniowano TERMINFO, i nazwa zaczyna się od ukośnika, to jest interpretowane jako nazwa pliku termcap, w którym należy szukać TERM; (3) gdy TERMINFO ma napis prowadzący, który wygląda jak lista wpisów nazw terminala i odpowiada TERM, to zawartość TERMINFO jest interpretowana jako termcap; (4) jeśli terminfo wygląda jak termcap, lecz nie zawiera TERM, plik termcap jest przeszukiwany wśród oddzielonych dwukropkami ścieżek TERMPATHS, o ile jest ono zdefiniowane i w ~/.termcap i ostatecznie w wartości plikowej TERMCAP_FILE.

Wersje curses, skompilowane na PC, wspierają znaki PC ROM (zawierające znaki 0-31, których curses z SVr4 nie potrafi wyświetlić). Zobacz sekcje ROZSZERZENIA w curs_addch(3x) i curs_attr(3x).

PRZENOŚNOŚĆ¶

Bibliotekę curses zaprojektowano jako zgodną ze standardem XSI Curses na poziomie podstawowym. Obsługiwane są pewne partie rozszerzonych XSI Curses (łącznie z obsługą koloru). Nie zaimplementowano jeszcze następujących wywołań rozszerzonego XSI Curses, związanych z obsługą szerokich (wielobajtowych) znaków: addnwstr, addwstr, mvaddnwstr, mvwaddnwstr, mvaddwstr, waddnwstr, waddwstr, add_wch, wadd_wch, mvadd_wch, mvwadd_wch, add_wchnstr, add_wchstr, wadd_wchnstr, wadd_wchstr, mvadd_wchnstr, mvadd_wchstr, mvwadd_wchnstr, mvwadd_wchstr, bkgrndset, bkgrnd, getbkgrnd, wbkgrnd, wbkgrndset, wgetbkgrnd, border_set, wborder_set, box_set, hline_set, mvhline_set, mvvline_set, mvwhline_set, mvwvline_set, whline_set, vhline_set, wvline_set, echo_wchar, wecho_wchar, erasewchar, killwchar, get_wch, mvget_wch, mvwget_ch, wget_wch, getwchtype, get_wstr, getn_wstr, wget_wstr, wgetn_wstr, mvget_wstr, mvgetn_wstr, mvwget_wstr, mvwgetn_wstr, innwstr, inwstr, winnwstr, winwstr, mvinnwstr, mvinwstr, mvwinnwstr, mvwinwstr, ins_nwstr, ins_wstr, mvins_nwstr, mvins_wstr, mvwins_nwstr, mvwins_wstr, wins_nwstr, wins_wstr, ins_wch, wins_wch, mvins_wch, mvwins_wch, in_wch, win_wch, mvin_wch, mvwin_wch, inwchstr, inwchnstr, winwchstr, winwchnstr, mvinwchstr, mvinwchnstr, mvinwchstr, mvwinwchnstr.

Niewielka ilość różnic (to jest poszczególnych różnic między XSI Curses, a wywołaniami curses) jest opisywana w sekcjach PRZENOŚNOŚĆ konkretnych stron podręcznika man.

Format terminfo, obsługiwany przez curses jest binarnie zgodny z SVr$, lecz nie jest zgodny z XSI curses. Jest tak, ponieważ ludzie od XSI Curses, w przypływie uszkodzenia mózgu, zmienili nieudokumentowaną właściwość SVr4 getm z napisu na wartość logiczną, zmieniając przez to offsety binarne wszystkich pozostałych właściwości.

Funkcje getmouse, mousemask, ungetmouse, mouseinterval i wenclose, związane z myszą, nie są częścią XPG4 ani SVr$. Zobacz dla dalszych szczegółów curs_mouse(3X).

Funkcja wresize nie jest częścią XPG4, i nie jest obecna w SVr4. Więcej szczegółów znajdziesz w curs_resize(3X).

W historycznych wersjach curses, opóźnienia zawarte we właściwościach cr, ind, cub1, ff i tab uaktywniały odpowiadające im bity opóźnień w UNIX-owym sterowniku tty. W tej implementacji wypełnianie jest dokonywane wysłaniami znaków NUL. Metoda ta jest trochę bardziej kosztowna, lecz znacząco zawęża interfejs z jądrem UNIX-a i odpowiednio do tego polepsza przenośność pakietu.

W standardzie XSI i w stronach podręcznika SVr4, wiele wpisów ma argumenty prototypopwe char *const (lub cchar_t *const, lub wchar_t *const, lub void *const). Zależnie od interpretacji standardu ANSI C (zobacz sekcję 3.5.4.1), deklaracje te są (a) bez znaczenia, lub (b) bez znaczenia i niedozwolone. Deklaracja const char *x to modyfikowalny wskaźnik do modyfikowalnych danych, lecz char *const x to niemodyfikowalny wskaźnik do modyfikowalnych danych. Ponieważ C przekazuje argumenty przez wartość, <typ> *const jako typ formalny jest co najmniej wątpliwy. Ta więc w tej implementacji zamieniono je globalnie na const <type> *.

UWAGI¶

Plik nagłówkowy <curses.h> automatycznie włącza pliki <stdio.h> i <unctrl.h>.

Jesli standardowe wyjście, programu curses jest przekierowywane do czegoś, co nie jest tty, odświeżenia ekranu będą kierowane na standardowe wyjście błędu. Jest to nieudokumentowana właściwość curses z AT&T SVr3.

AUTORZY¶

Zeyd M. Ben-Halim, Eric S. Raymond. Zejście z oryginalnych pcurses zrobił Pavel Curtis.

INFORMACJE O TŁUMACZENIU¶

Powyższe tłumaczenie pochodzi z nieistniejącego już Projektu Tłumaczenia Manuali i może nie być aktualne. W razie zauważenia różnic między powyższym opisem a rzeczywistym zachowaniem opisywanego programu lub funkcji, prosimy o zapoznanie się z oryginalną (angielską) wersją strony podręcznika za pomocą polecenia:

man --locale=C 3ncurses ncurses

Prosimy o pomoc w aktualizacji stron man - więcej informacji można znaleźć pod adresem http://sourceforge.net/projects/manpages-pl/.